.\" $Id: PAPI_get_dmem_info.3,v 1.6.12.1 2006/10/24 17:56:50 terpstra Exp $
.TH PAPI_get_dmem_info 3 "May, 2006" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_get_dmem_info \- get information about the dynamic memory usage of the current program

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_get_dmem_info(PAPI_dmem_info_t *" "dmem" ");"
.fi
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_get_dmem_info(C_LONG_LONG(*)\  dmem,\  C_INT\  check )
.fi

.SH DESCRIPTION
In C, this function takes a pointer to a PAPI_dmem_info_t structure and returns with the structure fields
filled in. In Fortran, this function takes a pointer to an array of long_long values and fills in the
array on return. A value of PAPI_EINVAL in any field indicates an undefined parameter.

.SH NOTE
This function is currently implemented only for the Linux operating system.

.SH ARGUMENTS
.LP
.I dmem
--  Structure (C) or array (Fortran) containing the following values 
(Fortran values can be accessed using the specified indices):
.LP
.B size [PAPIF_DMEM_VMSIZE] 
(Size of process image),
.LP
.B resident [PAPIF_DMEM_RESIDENT] 
(Resident set size),
.LP
.B high_water_mark [PAPIF_DMEM_HIGH_WATER]
(High water memory usage),
.LP
.B shared [PAPIF_DMEM_SHARED]
(Shared memory),
.LP
.B text [PAPIF_DMEM_TEXT]
(Memory allocated to code),
.LP
.B library [PAPIF_DMEM_LIBRARY]
(Memory allocated to libraries),
.LP
.B heap [PAPIF_DMEM_HEAP]
(Size of the heap),
.LP
.B locked [PAPIF_DMEM_LOCKED]
(Locked memory),
.LP
.B stack [PAPIF_DMEM_STACK]
(Size of the stack)
.LP
.B pagesize [PAPIF_DMEM_PAGESIZE]
(Size of a page in bytes),

.SH RETURN VALUES
On success, this function returns PAPI_OK with the data structure or array values filled in.
On error a negative error value is returned.

.SH ERRORS
.TP
.B "PAPI_ESBSTR"
The funtion is not implemented for the current substrate.
.TP
.B "PAPI_EINVAL"
Any value in the structure or array may be undefined as indicated by this error value.
.TP
.B "PAPI_SYS"
A system error occured.

.SH EXAMPLE
.LP
.nf
.if t .ft CW
   int retval;
   PAPI_dmem_info_t dmem;
   
   if (PAPI_library_init(PAPI_VER_CURRENT) != PAPI_VER_CURRENT)
   exit(1);

   retval = PAPI_library_init(PAPI_VER_CURRENT);
   if (retval != PAPI_VER_CURRENT)
      handle_error(retval);

   PAPI_get_dmem_info(&dmem);
   printf("Mem Size:\t\t%lld\n",dmem.size);
   printf("Mem Resident:\t\t%lld\n",dmem.resident);
   printf("Mem High Water Mark:\t%lld\n",dmem.high_water_mark);
   printf("Mem Shared:\t\t%lld\n",dmem.shared);
   printf("Mem Text:\t\t%lld\n",dmem.text);
   printf("Mem Library:\t\t%lld\n",dmem.library);
   printf("Mem Heap:\t\t%lld\n",dmem.heap);
   printf("Mem Locked:\t\t%lld\n",dmem.locked);
   printf("Mem Stack:\t\t%lld\n",dmem.stack);
   printf("Mem Pagesize:\t\t%lld\n",dmem.pagesize);
.if t .ft P
.fi

.SH BUGS
If called before 
.B PAPI_library_init()
the behavior of the routine is undefined.

.SH SEE ALSO
.BR PAPI_library_init "(3), "
.BR PAPI_get_opt "(3), " 
.BR PAPI_get_hardware_info "(3), "
.BR PAPI_get_executable_info "(3)"
